Inside Macintosh: QuickDraw GX Objects /

Chapter 2 - Shape Objects / Shape Objects Reference

Functions / Creating and Manipulating Shape Objects

GXNewShape

You can use the GXNewShape function to create a new shape of a specified shape type.

gxShape GXNewShape(gxShapeType aType);

aType

The type of shape object to create.

function result

A reference to a newly created copy of the default shape object of the type specified by the aType parameter.

DESCRIPTION

The GXNewShape function creates a copy of the default shape object of the type specified by the aType parameter and gives it an owner count of 1.

Although this function creates a copy of the default shape, it does not create a copy of the default shape's style, ink, or transform. The new shape returned by this function contains references to same style, ink, and transform as the default shape. You can change the style, ink, and transform of the shape by using the functions GXSetShapeStyle, GXSetShapeInk, and GXSetShapeTransform.

You can use this function by itself to create empty and full shapes. For other shape
types, you can use this function to create a shape and then you can customize the shape's geometry by using additional functions, such as GXSetShapeGeometry or one of the shape-specific functions such as GXSetPoint, GXSetLine, GXSetPathParts, or GXSetGlyphParts.

SPECIAL CONSIDERATIONS

If no error occurs, the GXNewShape function creates a shape object; you are responsible for disposing of that object when you no longer need it.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
illegal_type_for_shape	(debugging version)

SEE ALSO

Shape types, including empty and full shapes, are described in the section "Shape Type" beginning on page 2-9.

Default shape objects are discussed in the section "Default Shapes" beginning on page 2-18. To examine a default shape, use the GXGetDefaultShape function, described on page 2-52. To replace a default shape, use the GXSetDefaultShape function, described on page 2-53.

The GXSetShapeStyle function is described on page 2-70; the GXSetShapeInk function is described on page 2-71; the GXSetShapeTransform function is described on page 2-73.

The GXSetShapeGeometry function is described on page 2-67. Other geometry-setting functions are described in the shape-specific chapters of Inside Macintosh: QuickDraw GX Graphics and Inside Macintosh: QuickDraw GX Typography.

For an example of the use of this function, see page 2-24.